home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 11
/
Cream of the Crop 11-1.iso
/
comm
/
bgfax155.zip
/
BGFAX.DOC
< prev
next >
Wrap
Text File
|
1996-01-08
|
56KB
|
1,123 lines
DON'T FORGET TO LOOK AT THE "READ.ME" AND "WHATS.NEW" FILES!
=======================================================================
Voice B.J. Guillot Data/Fax
+1 713.893.9320 2611 Rushwood Circle +1 713.893.9124
Houston Texas 77067-1941
Copyright (C) 1993-1996 B.J. Guillot. All Rights Reserved.
=======================================================================
BGFAX 1.55 MON 8 JAN 96
=======================================================================
Dedicated to Gene Roddenberry
1921-1991
"It wasn't a miracle... We just decided to go."
-- Tom Hanks, playing Jim Lovell in APOLLO 13,
referring to the Apollo 11 moon landing.
"Let's make sure history never forgets the name, ENTERPRISE."
-- Captain Jean-Luc Picard. Star Trek: The Next Generation.
"...Humans and aliens wrapped in two million, five hundred
thousand tons of spinning metal, all alone in the night..."
-- Commander Sinclair. BABYLON 5.
"I am Pentium of Borg. Division is futile. You will be
approximated."
-- unknown, relating to the FPU bug in early Pentium 60's
-------------------------------------------------------------
ABSTRACT/FEATURES
-------------------------------------------------------------
* Allows sysops to receives faxes on their BBS telephone line
without needing any additional hardware!
* Can send faxes via the command line and return status by
errorlevel; fully configurable top of page headers on outgoing
faxes so that user names and phone numbers can be added
* Everything runs in the foreground, no TSR programs needed
* If you are already running a Fido mailer, you can configure
your mailer to exit and run BGFAX when the line is hot, thus
BGFAX does not necessarily have to answer the phone itself
* Comes with a small and quick fax viewing program that supports
CGA, EGA, VGA, and VESA SVGA display modes as well as options
for fax printing and FAX-to-PCX conversion; it even can use XMS!
[ See VIEW.DOC for more information ]
* Works with modems that offer a feature known as adaptive
answering on Class 1, Class 2, Class 2.0 and ZyXEL fax modems
* Multitasker aware; releases ticks to DesqView and OS/2
-------------------------------------------------------------
INCLUDED FILES
-------------------------------------------------------------
1. DOCS\BGFAX.DOC -- general documentation, looking at it now
2. READ.ME -- read this
3. WHATS.NEW -- release notes
4. BGFAX.EXE -- the main DOS executable
5. BGFAX2.EXE -- the main OS/2 executable
6. VIEW.EXE -- fax viewing, PCX and DCX conversion,
and PRINTING functions
7. VIEW.DOC -- documentation to the view.exe program!
8. NFAX.COM --\ optional TSR utility to notify the user
9. FAXOFF.COM --/ if a fax has been received (DOS ONLY)
10. MAKEFAX.EXE -- converts PCX and ASCII files to ZFAX format
11. MAKEFAX2.EXE -- same thing, but for OS/2
12 BGFAX.FNT -- font file for MAKEFAX and MAKEFAX2
13. FNTEDIT.EXE -- font editor to make customized fonts (DOS ONLY)
14. BGFAX.CNF -- configuration file for /SEND and /HOST
15. FBBS.BAT -- example batch file for using /HOST mode
16. REGISTER.FRM -- registration form
17. REGISTER.NL -- dutch registration form for the netherlands
18. REGISTER.AUS -- australian registration form
19. DOCS\WIREXFER.FRM -- bank info needed for wire transfers
Several *.TXT files that describe setting up BGFAX step-by-step
for various BBS systems, mailers, etc. See the DOCS\ directory.
-------------------------------------------------------------
DISCLAIMER
-------------------------------------------------------------
BGFAX and accompanying files are provided AS IS without any
warranty, expressed or implied. This includes without limitation
the fitfulness for a particular purpose or application and any
warranties of merchantability. [Did you really understand that?]
While I tried to be as through as possible in preparing BGFAX,
B.J. Guillot shall not be liable for any damages, whether direct,
indirect, special, incidental or consequential arising from a
failure of this program or accompanying files to operate in a
manner desired by the user. B.J. Guillot shall not be liable for
any damage to data or property which may by caused directly or
indirectly by use of this program.
In no event will B.J. Guillot be liable to you for any damages,
including any lost profits, lost savings or other incidental or
consequential damages arising out of your use or inability to use
the program, or for any claim by any other party. Individuals using
the software bear all risk as to its quality and performance.
-------------------------------------------------------------
OBTAINING THE LATEST VERSION OF BGFAX:
-------------------------------------------------------------
FidoNet: 1:106/400 Voice: +1 713.893.9320
InterNet: bjg90783@jetson.uh.edu BBS: +1 713.893.9124
1. Calling my BBS in the United States, +1 713-893-9124
2. Internet... FTP: ftp://ftp.csn.net/Computech
World Wide Web: http://www.blkbox.com/~bgfax
3. FidoNet FREQ of the magic name "BGFAX" from 1:106/400
(Beta copies are available under magic name "BGBETA")
4. FidoNet FREQ... The Netherlands... 2:512/39
The Owl's Nest is the Dutch Supra distributor and they
have three nodes:
+31 0.2155.10921 +31 0.2155.12571 +31 0.2155.28096
5. FidoNet FREQ... Austraila... 3:632/552
Hamish Moffatt, Cloud Nine, +61 03.886.5195
6. E-mail request for users that do not have FTP access...
Just send Internet e-mail to "bgfax-request@stat.com"
(Beta copes are available from bgfax-beta-request@stat.com)
-------------------------------------------------------------
MISCELLANEOUS NOTES
-------------------------------------------------------------
Modems that I have direct access to:
SupraFaxModem v.32bis (V1.80-02, Rockwell AC ROM)
SupraFaxModem 144 Express Plus
SupraFaxModem 288 V.FC (FLASH firmware, latest version)
SupraFaxModem 288 V.34 (FLASH firmware, latest version)
USR Courier V.Everything (FLASH firmware, latest version)
Hayes Optima 288 V.34 (V3.1 firmware)
SIERRA based 2400 data/9600 fax modem from Computer City
*************************************************************************
*************************************************************************
The *.TXT files provide step-by-step setup instructions for most
mailers and BBS software. You probably will not have to read the
rest of this documentation.
*************************************************************************
*************************************************************************
-------------------------------------------------------------
/HOST MODE
-------------------------------------------------------------
If you want BGFAX to answer the phone, BGFAX is started up using
the /HOST command line parameter.
If you plan on using BGFAX in Frontend mode, you need to do a
couple of things first.
1. Make sure your BGFAX environment variable is set to a valid
directory. See the included FBBS.BAT file. Example...
SET BGFAX=C:\BGFAX
This environment variable points to the location of your BGFAX
configuration file and the directory where faxes will be
received into.
2. Make sure the BGFAX.CNF configuration file is in the directory
pointed to by the BGFAX environment variable and make any
changes you think necessary. The included configuration file
is self explanatory. I won't repeat the format here.
3. BGFAX can exit with 7 possible internal errorlevels:
6 - /HOST:nn mode has been idle for more than nn minutes
4 - fax was received
3 - local logon
2 - data call
1 - restart the FBBS.BAT batch file
If no errorlevel is encountered, it means the sysop aborted
BGFAX by pressing the [Esc] key or a serious error occurred.
Actually, BGFAX can exit with several errorlevels if you setup
events. Events are specified in the BGFAX.CNF file (see the
example file included). Example:
ev=07:00,192
ev=19:00,193
That would cause BGFAX to exit with errorlevel 192 at 7:00am
and errorlevel 193 at 7:00pm. BGFAX's event handling is very
crude, and I very much need to change it. The event handling
still has several bugs that need to be fixed. It works best if
you use a total of two events. One event doesn't work very
well, and if you use more (up to 20 are allowed), you can miss
an event or two if a caller to your BBS overstays their visit.
BGFAX will always execute the first event that is passed over,
but won't do any more. And, if you only have one event setup,
it will not execute that one if it is missed. But it will, if
you set up two events. You can probably tell I hate events.
If anyone has some ideas on how to keep track of events and
execute the ones that are missed, etc., I'd appreciate it.
4. When BGFAX is waiting for a call, pressing Ctrl-R will reset
the on screen counters. Ctrl-A will force BGFAX to send the
answer string to the modem.
6. When a data call comes in, BGFAX creates a DOBBS.BAT file that
looks like so...
C:\BGFAX\EXEBBS.BAT 9600 1 528 /ARQ
BGFAX/2 will create DOBBS.CMD instead of a BAT file ...
C:\BGFAX\EXEBBS.CMD 9600 5 528 /ARQ
The first parameter is the DCE data speed, then the com port,
number of minutes until the next event, and then the error
correcting string, if any. The EXEBBS.BAT file must be created
by you so that your bulletin board software is loaded up in
frontend mode (ie., the data connection is already hot.)
%1 -> the DCE speed, modem-to-modem real connect speed
%2 -> the COM port (BGFAX/2 will put the OS/2 com handle)
%3 -> number of minutes until the next event
%4 -> error correction/reliable mode indicators
DOBBS.BAT theory
================
If you have never used a frontend program uses DOBBS.BAT theory,
there are several things you need to know. You have to be pretty
confident in DOS and batch files, or you will get lost very
easily. First, you need a main batch file that runs BGFAX. Let's
call this FBBS.BAT:
@echo off
rem ***** This is an example batch file for frontend mode operation
set bgfax=c:\bgfax
c:
cd %bgfax%
bgfax /host
if errorlevel 120 maint1.bat
if errorlevel 4 goto faxrcvd
if errorlevel 3 goto datacall
if errorlevel 2 goto datacall
if errorlevel 1 fbbs.bat
goto end
:faxrcvd
rem ***** You can auto-print every fax, see docs for info on EXEPRINT.BAT
call %bgfax%\doprint.bat
del %bgfax%\doprint.bat
fbbs.bat
:datacall
rem ***** Errorlevel 2 = Data Call, Errorlevel 3 = Local Logon
rem ***** The following line executes the DOBBS.BAT file created by BGFAX
rem ***** which then runs EXEBBS.BAT which should load your BBS software.
%bgfax%\dobbs.bat
:end
--> Note that DOS requires all if-errorlevel statements to go in
--> DESCENDING ORDER! (255,254,253,...,4,3,2,1). This is a fact that
--> many people forget.
This FBBS.BAT file will run BGFAX and when a data caller calls
your system, BGFAX will exit with an errorlevel of 3. This will
cause the batch file to jump to the ":datacall" label. Here, the
line "%bgfax%\dobbs.bat" is executed, causing DOS to shift control
of the computer to the DOBBS.BAT file. Remember, this is a file
that BGFAX creates! You do not need to make a DOBBS.BAT file.
The DOBBS.BAT then executes _another_ batch file called EXEBBS.BAT
which will look something like:
EXEBBS.BAT
==========
@echo off
bbsprog /f:%1:%2
fbbs
!!! THE EXEBBS.BAT FILE WILL LOOK DIFFERENT FOR EVERY DIFFERENT
TYPE OF BBS SOFTWARE !!!
You will have to look up the info for the EXEBBS.BAT file in
your BBS user's manual. I can't help you with that. Notice
that the last line "fbbs" restarts the original FBBS.BAT
file that runs BGFAX in /HOST mode.
In review: (1) Modify FBBS.BAT to meet your needs, (2) BGFAX will
MAKE a DOBBS.BAT file by itself, (3) YOU will need to MAKE an
EXEBBS.BAT file, (4) the EXEBBS.BAT file must restart FBBS.BAT.
Do not use the CALL statement anywhere unless you really know what
you are doing. "FILE.BAT" and "CALL FILE.BAT" causes two
completely different things to happen. Only experienced DOS/batch
file writers need to experiment with that. Example:
TEST.BAT
========
echo **TEST**
EXAMPLE1.BAT Example1.BAT output:
===========
echo Hello World! Hello World!
call test.bat **TEST**
echo Bye World! Bye World!
rem ***We RETURNED to the batch file after TEST.BAT
EXAMPLE2.BAT Example2.BAT output:
============
echo Hello World! Hello World!
test.bat **TEST**
echo Bye World!
rem ***We DID NOT RETURN to the batch file after TEST.BAT
-------------------------------------------------------------
REAR END MODE (FIDO MAILERS, ETC.)
-------------------------------------------------------------
Rear end mode is useful for those of us who are FidoNet members
where a Fido mailer is required to be running 24 hours a day. It
will be your job to figure out how to get your mailer to exit to
BGFAX when your modem informs the mailer a fax call is coming
through. (See the *.TXT files for hints on specific mailers.)
Note that in rear-end mode, the BGFAX.CNF file is NOT used.
The BGFAX environment variable is not required either, but if
it is present in rear-end mode, the BGFAX.LOG will be saved
into the path that is pointed to by the BGFAX environment
variable. Otherwise, the BGFAX.LOG is saved into the path that
is pointed to as specified on the command line (see below).
You will need to know the result code your modem sends when an
incoming fax call is detected. Some modems send TWO fax connect
strings. For example, the Supra will send "FAX" followed by an
"+FCON" response about 2 seconds later. The ZyXEL will send
"CONNECT FAX" followed immediately by "ZyXEL". Most fax modems
report only one string though. Use this chart for reference:
Result Modems
====== ====================================================
FAX Supra, Zoom, Hayes, most Rockwell based chipsets
+FCON PPI, Intel, GVC, some other Class 2 modems
+FCO USR V.Everything and other Class 2.0 modems
^
THAT IS NOT A ZERO!! IT'S THE LETTER "OH"!
You need to configure your mailer (or BBS software) to exit
IMMEDIATELY upon receipt of the proper fax result code. You
need to call BGFAX in the following manner:
BGFAX /how faxpath port faxtype
FAXPATH will be the directory where incoming faxes are to be
placed. PORT is a valid communications port from 1 to 4, or,
optionally, a hexidecial base address and IRQ formatted as
followed "3F8x5". Also, optionally, if the port has a bang, !,
following it, it will force the port to stay locked at the current
speed rather than shifting to 19200 on fax connects. FAXTYPE is a
single character 'Z' or 'Q'.
'Z' for ZyXEL ZFAX format,
'Q' for Smith Micro Software's Quick Link II fax format,
'F' for TIFF Class F, specially, Faxworks for OS/2 format.
The "/how" deal is the most critical switch. There are many
possible settings.
/FAX ... Modem reports "FAX" or "CONNECT FAX".
BGFAX will automatically detect whether it should
use Class 2 (Supra, Zoom) or the ZyXEL fax mode
based on the next message (ie, "+FCON" or "ZyXEL").
/FAX:713_555_1212 If your modem in Class 1, try one of
/FHAY:713_555_1212 these two options.
/FAST:nn .... Modem reports "+FCON" (PPI, other Class 2 modems)
/FCO:nn ..... Modem reports "+FCO" (USR V.Everything)
/FZYX ....... ZyXEL owners use this if /FAX doesn't work.
THE "nn" WILL BE A NUMBER IN SECONDS!
Here is a schematic of how each option behaves:
*** /FAX [ Supra, ZyXEL, i.e. all modems that report "FAX" ]
1. keeps port at locked DTE 1. <same> 1. <same>
2. waits for "+FCON" _or_ 2. waits for "OK" _or_ 2. waits for "ZyXEL"
3. drops port to 19200 3. sends "AT+FDR" 3. waits for high CTS
4. waits for "OK" 4. sends <DC2>
5. sends "AT+FDR"
*** /FAX:713_893_9124 [ Supra LC modem, Class 1 modem ]
1. keeps port at locked DTE
2. waits for "CONNECT"
3. begins sending Class 1 HDLC frames
*** /FHAY:713_893_9124 [ Hayes 288, other Class 1 modems ]
1. keeps port at locked DTE
2. blindly starts sending Class 1 HDLC frames
*** /FAST:nn [ all Class 2 modems where /FAX won't work ]
Let's present we use /FAST:4 ...
1. drops port to 19200
2. waits for "OK" for nn seconds (FOUR seconds if /FAST:4)
3. if "OK" occurs before nn seconds, sends AT+FDR
_or_
3. if "OK" is not received in nn seconds,
blindly sends AT+FDR
*** /FCO:nn [ USR, i.e., all Class 2.0 modems that report "+FCO"]
This switch is a hybrid of the /FCO and /FCOS switches.
Let's pretend we use /FCO:4 ...
1. keeps port at locked DTE
2. waits for "OK" for nn seconds (FOUR seconds if /FCO:4)
3. if "OK" occurs before nn seconds, sends "AT+FDR"
_or_
3. if "OK" is not received in nn seconds,
blindly sends "AT+FDR"
*** /FZYX [ ZyXEL, use this only if /FAX doesn't work ]
1. waits for high CTS
2. sends <DC2>
NOTE: /FCO:0 is equivilant to the old /FCOS switch
/FAST:0 is equivilant to the old /FCON switch
When a fax is inbound, here are some example BGFAX command
lines for rear-end mode operation on my Supra:
a. BGFAX /FAX C:\BGFAX 1 Z
b. bgfax /fax c:\bgfax f3 z
c. bgfax /fax c:\bgfax 3f8x7 z
d. bgfax2 /fax c:\bgfax h%3 z
Here is how the above four options differ:
a. Uses COM1
b. Uses FOSSIL port COM3 (many FOSSILs refer to this as Port 2)
c. Uses non-standard port configuration at hex address 3f8 and
using hardware IRQ 7.
d. OS/2 version, using a com handle ("h") of whatever is passed
by the %3 variable. The com handle cannot be translated into
a port number, so it must be passed by the OS/2 BBS or OS/2
Fido mailer software.
Using my Hayes 288, example command line options might be:
bgfax /fhay:713_555_1212 c:\bgfax 1 z
...note that the ID string MUST be presented on the command line
when you are receiving with a Class 1 modem in rear end mode.
In Class 1, the fax software is responsible for sending the ID
string to the remote machine. (In contrast to Class 2/2.0 modems,
which automatically send the ID to the remote machine.)
The /FAX means that I used the modem response "FAX" as a trigger
for FD (see FD212.TXT for more details), C:\BGFAX is the path
where I want all faxes to be stored, "1" is the communications
port, and the "Z" represents I want faxes saved in ZyXEL's ZFAX
image format.
-------------------------------------------------------------
CLASS 1 RECEIVING AND THE /DIS:NNN SWITCH
-------------------------------------------------------------
Telling Class 1 modems to receive at a maximum of 9600 bps /DIS
================================================================
If your Class 1 modem can receive at a maximum of 9600, strange
things will happen if you forgot to tell BGFAX this, since it will
default to tell the other side you will be using 14400 bps for fax
operations. To force BGFAX to receive at a maximum of 9600 bps
with Class 1 faxmodems, use the /DIS:79 parameter, i.e.:
bgfax /fhay:713_893_9124 c:\bgfax 1 z /dis:79 /ns
To compute your own /DIS value, first, pick a value from the
following table:
2400 -> 3
4800 -> 11
9600 -> 15
14400 -> 47
Next, you have two options. If you want to allow high resolution
documents, add the value 64 to your choice. If you want to allow
2D-MR documents, add the value 128 to your choice. For example,
let's say you wanted a maximum speed of 9600 along with high
resolution documents: 15 + 64 = 79, so use /DIS:79.
See the following chart for pre-computed examples:
/DIS:nnn Description (all of the following allow high res faxes)
-------- -------------------------------------------------------
75 Maximum speed of 4800 bps, 1D-MH faxes only
79 Maximum speed of 9600 bps, 1D-MH faxes only
207 Maximum speed of 9600 bps, 1D-MH & 2D-MR faxes
111 Maximum speed of 14400 bps, 1D-MH faxes only [DEFAULT]
239 Maximum speed of 14400 bps, 1D-MH & 2D-MR faxes
-------------------------------------------------------------
TSR fax notification
-------------------------------------------------------------
BGFAX comes with an optional TSR program (NFAX.COM) that will
place the word "FAX" on your screen whenever a successful incoming
fax occurs. However, you must tell BGFAX that you wish to alert
NFAX.COM to display the message. You can do this by using the /NF
switch. Example:
bgfax /fax c:\bgfax 2 q /nf
This will activate the NFAX.COM interrupt and cause the message to
get displayed. To turn the message off, you can run the FAXOFF.COM
program contained in the BGFAX archive. Remember, NFAX.COM is a
TSR and must be loaded in your AUTOEXEC.BAT properly if you wish
to use it with BGFAX. It is totally optional! Also, note that if
your machine is rebooted, the fax message will not be on your
screen when your system powers back up.
NFAX.COM/FAXOFF.COM technical information:
===========================================
Here is a snip of the Turbo Pascal source code that tells NFAX.COM
to put the fax indicator on the screen:
var
regs : registers;
begin
writeln('Activating "NFAX" interrupt.');
regs.ah := 30; { nfax-function }
regs.al := 21; { nfax-sub function }
regs.bl := 95; { nfax-"FAX" attribute, white on purple }
intr($55, regs); { nfax-tsr }
end;
When you want to turn off the "FAX" alert message, you need to
run the included "FAXOFF.COM" file. It basically issues the
same code above except that "regs.al := 22" instead of 21.
(Go into DEBUG and do an unassemble on the .COM file to see
exactly how to turn it off.)
************************************************************************
AFTER YOU RECEIVE THE FAX
************************************************************************
NAMING CONVENTION
=================
The name of the fax file will be FAXnnnn.??? where "nnnn" is a
number that is padded with zeros and "???" is "FAX" or "QFX",
depending upon which fax format you save the file in. If you ever
see a BGFAX.$$$ file in your directory, it should *NOT* be there,
as it should have been renamed in the FAXnnnn.??? format. If it
is there, it means some kind of problem happened during the fax
reception. Normally, problem faxes will be renamed to BADnnnn.???.
Faxworks format files are named FXnnnnn.FAX.
FAXIN.LOG
=========
BGFAX creates a BGFAX.LOG file that contains a bunch of
information that is mainly only for debug purposes. A much
cleaner log file is called FAXIN.LOG and looks like this:
Date Time ET Bytes Rate Filename Remote Fax ID Pgs Notes
-------------------------------------------------------------------------------
12-21 11:52 00:42 18183 9600*FAX0001.FAX Unknown 2 Finished
12-21 18:04 00:38 18182 9600 FAX0002.FAX Unknown 2 Not Done
12-22 21:30 00:29 17793 14400*FAX0003.FAX 7138939124 1 Finished
12-22 21:42 00:29 17541 14400#FAX0004.FAX TRANQUILITY BASE 1 Finished
12-23 06:44 00:32 16941 9600%FAX0005.FAX Null ID Received 1 Finished
12-25 17:21 01:22 107392 14400*FAX0006.FAX 7132424708 1 Finished
Notice the special symbols between the Rate and Filename:
-> (space) means low resolution, 1D-MR compression
* -> means high resolution, 1D-MH compression
% -> means low resoltion, 2D-MR compression
# -> means high resolution, 2D-MR compression
"Not Done" under Notes means that BGFAX believed more pages were
to have followed, but were not actually received. "ET" is
estimated time. Everything else is self explanatory.
DOPRINT.BAT
===========
After you successfully receive a fax, BGFAX will exit with an
errorlevel of 4 and append (or create) a DOPRINT.BAT file.
CALL C:\BGFAX\EXEPRINT.BAT C:\BGFAX\FAX0085.FAX
CALL C:\BGFAX\EXEPRINT.BAT C:\BGFAX\FAX0086.FAX
You do not have to do anything with this at all, but it is
provided for those of you who wish to print faxes as they are
received. It will call the EXEPRINT.BAT file and pass it the
parameter with the path and name of the fax file that was just
received.
@echo off
rem ... following line prints to a laser
view %1 /p40
rem ... following line prints to a 24-pin dot matrix
rem view %1 /p24
Remember to delete the DOPRINT.BAT file after you process it.
(If you do not, every time BGFAX goes to print another fax,
it will print ALL faxes received since you first set it up.)
-------------------------------------------------------------
SEND FAX MODE
-------------------------------------------------------------
Currently, if you want to send a fax to another person, the fax
file must already be in either ZFAX or Quick Link II fax image
format.
BGFAX /SEND FAX0001.FAX 893-9124
See the BGFAX.CNF file for more info, such as maximum amount of
busy signals and failures before exit, etc.
At this time, only previously converted fax files can be sent.
(i.e., ASCII files have to be translated to ZFAX .FAX format or
QLII .QFX format.) You can use the included MAKEFAX.EXE program
to convert an ASCII file to .FAX format. MAKEFAX.EXE will require
that the font file BGFAX.FNT exists in your BGFAX directory.
MAKEFAX allows a width of up to 100 characters per line. (Use
the /SP command line parameter on MAKEFAX if you want it to use
short sized pages for pages in the fax that aren't fully used.)
BGFAX can exit with three possible errorlevels when sending...
errorlevel 5 -> fax sent successfully
errorlevel 1 -> fax send failure
no errorlevel -> file not found, keypress abort, etc.
If the number is BUSY, BGFAX will try a few more times (the number
of times specified in the MB= entry in the BGFAX.CNF file) and
will pause for SW= number of seconds between dials. If a failure
occurs during handshaking or during the actual sending of the fax,
BGFAX will terminate with an failure errorlevel.
If you are a programmer, and need to use BGFAX to send faxes, but
need more information than success or failure, you need to use the
/ER switch on the BGFAX /SEND command line. BGFAX will make only
ONE attempt to send the fax in /ER mode (regardless of BUSY, etc.)
bgfax /send fax0001.fax 893-9124 /er
The following "Extended Results" are available:
errorlevel 19 -> too many retrains (a class 1 failure)
errorlevel 18 -> remote ID fails the /CI:xxx match
errorlevel 17 -> remote fax device does not support 2D-MR
errorlevel 16 -> remote fax does not support high resolution
errorlevel 15 -> failure after connect (HDLC frameout, etc.)
(a class 1 failure)
errorlevel 14 -> a timeout occurred
errorlevel 13 -> no +FCON ever occurred (NO CARRIER, etc.)
(a class 2 or 2.0 failure)
errorlevel 12 -> failure after connect (+FHNG, no XON, etc.)
(a class 2 or 2.0 failure)
errorlevel 11 -> "NO DIALTONE"
errorlevel 10 -> "BUSY"
errorlevel 7 -> the number is BLACKLISTED by the modem
errorlevel 5 -> *** FAX SENT SUCCESSFULLY ***
errorlevel 1 -> generic fax send failure
no errorlevel -> keypress abort, unknown failure type
TOP OF PAGE HEADERS
===================
BGFAX will print a top of page header at the top of each page
BGFAX sends out. This is same time of things that real fax
machines and other computer fax software do that identify who sent
the fax, where it's going, the date and time, and the page number.
BGFAX will need to call MAKEFAX.EXE with a special command line
parameter to cause the creation of the top of make banners. Make
sure you keep both MAKEFAX.EXE and BGFAX.FNT in your BGFAX
environment directory.
If you get lost real easy, you can skip the rest of this section.
This rest of this section describes how to configure BGFAX to
change the format of the top of page banners.
BGFAX lets you be very flexible with what exactly is said on the
top of page headers. It does this by the use of a "template" that
is located in the BGFAX.CNF file. This is necessary so that
countries that do not use English can put their own language on
the top of page banners. Also, it's just plain fun.
fh=To: %to21% From: %fr42% %mo2%/%dy2%/%yr2% %hr2%:%mi2% Pg %pg2%/%mp2%
fr=B.J. Guillot (713-893-9124)
The fh= entry is the template.
It should be obvious as to what all those %TTNN% things do,
but if not, here's a little dictionary:
%toNN% -> who the fax is for (will default to the sending phone number,
but can override to say any text with the /TO= command line switch)
%frNN% -> who the fax if from (will default to the ID= entry in the
BGFAX.CNF file, unless a FR= entry is found, but can override to say
any text with the /FR= command line switch)
%moNN% -> month
%dyNN% -> year
%hrNN% -> hour
%miNN% -> minute
%pgNN% -> current page number
%mpNN% -> maximum number of pages
With %to and %fr, BGFAX will right pad the whoto or whofrom strings to
a total number of NN characters with blanks. All other fields, are
left padded to NN characters with ZEROS. Keep in mind that BGFAX can
fit 100 characters across the page.
The fr= option, is used in the fh= template entry. Basically,
fr= is what will be inserted into the %frNN% template variable.
Are you lost? Here is an example and what it would look like:
C:\> bgfax /send output.fax 555-1212
To: 555-1212 From: B.J. Guillot (713-893-9124) 05/08/94 16:25 Pg 01/15
Let's say you run a BBS with a fax door and want to stick you
user's name at the top of each page instead of your personal name.
No need to rebuild a BGFAX.CNF! You can manipulate the %toNN% and
%frNN% template variables from the command line. If you do this,
remember to use underscores (_) to indicate spaces. Example:
C:\> bgfax /send output.fax 555-1212 /fr=BGFAX_Tech_Support /to=John_Doe
To: John Doe From: BGFAX Tech Support 05/08/94 16:25 Pg 01/15
LIMITING MAXIMUM /SEND SPEED
============================
/SEND:nnnn Some fax machines and fax modems don't operate very well together
at 14400 speeds. You can force BGFAX to use a lower maximum speed
by putting the BPS rate after the send command, e.g.:
bgfax /send:9600 fax0001.fax 893-9124 /c1
bgfax /send:7200 fax0001.fax 893-9124
bgfax /send:12000 fax0001.fax 1-713-893-9124
FAXOUT.LOG
==========
A FAXOUT.LOG file is created when sending out faxes to indicate
the success or failure. Here is an example:
Date Time ET Bytes Rate Filename Phone Number Pgs Notes
-------------------------------------------------------------------------------
03-22 13:18 00:25 3882 14400 RESPOND.FAX 8939124 2 Finished
03-22 13:18 00:11 3884 NOFAX RESPOND.FAX 8939124 0 Busy
03-22 13:19 00:11 3884 NOFAX RESPOND.FAX 8939124 0 No Fcon
03-22 13:30 00:31 3208 7200 RESPOND.FAX 8939124 0 Bad Conn
03-22 13:31 00:28 3882 9600 RESPOND.FAX 8939124 2 Finished
03-23 14:42 00:26 3882 14400 RESPOND.FAX 8939124 1 Timeout
03-23 14:44 00:29 3882 NOFAX RESPOND.FAX 8939124 0 BlackLst
03-23 14:47 00:21 3882 NOFAX RESPOND.FAX 8939124 0 Max Busy
03-23 14:51 00:23 3882 14400 RESPOND.FAX 8939124 1 Gen Fail
03-23 14:54 00:05 3882 NOFAX RESPOND.FAX 8939124 0 No Dial
-------------------------------------------------------------
HANGUP STATUS CODES
-------------------------------------------------------------
When BGFAX reports "Problematic fax reception", it will indicate a
fax hangup code, such as [+FHNG: 73]. This chart, taken from the
Supra CLASS_2.TXT fax command set documentation (which, I believe
was taken from the Rockwell Class 2 documentation), allows you to
match up the +FHNG message with its true meaning. For example,
+FHNG: 73 would indicate "T.30 T2 timeout, expected page not
received", which really does not say much, but it may give you
some clue. I don't know what most of these mean myself, so I
don't know whether it will provide you any luck or not, but, many
people asked that it be included, so here it is.
/-----------------------------------------------------------------\
| 2.0 Class 2 | Cause Description |
| --------------|-------------------------------------------------|
| 00-0F 0-9 | CALL PLACEMENT AND TERMINATION |
|---------------|-------------------------------------------------|
| 00 0 | Normal and proper end of connection |
| 01 1 | Ring Detect without successful handshake |
| 02 2 | Call aborted, from +FK/+FKS or <CAN> |
| 03 3 | No Loop Current |
| 04 4,n/a | Ringback detected, no answer (timeout) |
| 05 n/a | Ringback detected, answer without CED |
|---------------|-------------------------------------------------|
| 10-1F 10-19 | TRANSMIT PHASE A & MISCELLANEOUS ERRORS |
|---------------|-------------------------------------------------|
| 10 10 | Unspecified Phase A error |
| 11 11 | No Answer (T.30 T1 timeout) |
|---------------|-------------------------------------------------|
| 20-3F 20-39 | TRANSMIT PHASE B HANGUP CODES |
|---------------|-------------------------------------------------|
| 20 20 | Unspecified Transmit Phase B error |
| 21 21 | Remote cannot receive or send |
| 22 22 | COMREC error in transmit Phase B |
| 23 23 | COMREC invalid command received |
| 24 24 | RSPEC error |
| 25 25 | DCS sent three times without response |
| 26 26 | DIS/DTC received 3 times; DCS not recognized |
| 27 27 | Failure to train at 2400 bps or +FMS/ |
| | +FMINSP value |
| 28 28 | RSPREC invalid response received |
|---------------|-------------------------------------------------|
| 40-4F 40-49 | TRANSMIT PHASE C HANGUP CODES |
|---------------|-------------------------------------------------|
| 40 40 | Unspecified Transmit Phase C error |
| 41 n/a | Unspecified Image format error |
| 42 n/a | Image conversion error |
| 43 43 | DTE to DCE data underflow |
| 44 n/a | Unrecognized Transparent data command |
| 45 n/a | Image error, line length wrong |
| 46 n/a | Image error, page length wrong |
| 47 n/a | Image error, wrong compression code |
|---------------|-------------------------------------------------|
| 50-6F 50-69 | TRANSMIT PHASE D HANGUP CODES |
|---------------|-------------------------------------------------|
| 50 50 | Unspecified Transmit Phase D error |
| 51 51 | RSPREC error |
| 52 52 | No response to MPS repeated 3 times |
| 53 53 | Invalid response to MPS |
| 54 54 | No response to EOP repeated 3 times |
| 55 55 | Invalid response to EOP |
| 56 56 | No response to EOM repeated 3 times |
| 57 57 | Invalid response to EOM |
| 58 58 | Unable to continue after PIN or PIP |
|---------------|-------------------------------------------------|
| 70-8F 70-89 | RECEIVE PHASE B HANGUP CODES |
|---------------|-------------------------------------------------|
| 70 70 | Unspecified Receive Phase B error |
| 71 71 | RSPREC error (before TCF??) |
| 72 72 | COMREC error (after TCF??) |
| 73 73 | T.30 T2 timeout, expected page not received |
| 74 74 | T.30 T1 timeout after EOM received |
|---------------|-------------------------------------------------|
| 90-9F 90-99 | RECEIVE PHASE C HANGUP CODES |
|---------------|-------------------------------------------------|
| 90 90 | Unspecified Receive Phase C error |
| 91 91 | Missing EOL after 5 seconds |
| n/a 92 | < Not assigned > /--- Rockwell only |
| 92 -Note-> 94 | Bad CRC or frame (ECM {or BFT} modes) |
| 93 93 | DCE to DTE buffer overflow |
|---------------|-------------------------------------------------|
| A0-BF 100-119 | RECEIVE PHASE D HANGUP CODES |
|---------------|-------------------------------------------------|
| A0 100 | Unspecified Receive Phase D errors |
| A1 101 | RSPREC invalid response received |
| A2 102 | COMREC invalid response received |
| A3 103 | Unable to continue after PIN or PIP |
|---------------|-------------------------------------------------|
| C0-DF n/a | RESERVED FOR FUTURE STANDARDIZATION |
| E0-FF n/a | RESERVED FOR MANUFACTURER SPECIFIC USE |
| n/a 120-255 | RESERVED CODES |
\-----------------------------------------------------------------/
-------------------------------------------------------------
LIST OF ALL COMMAND LINE PARAMETERS, SHORT DESCRIPTIONS
------------------------------------------------------------
"REAR" refers to BGFAX's rear-end mode, usually when a BBS
or Fido mailer answers the phone, and then passes control to
BGFAX when the port is still hot. This refers to /FAX, /FAST,
/FCO, /FHAY and /FZYX modes.
Valid in /HOST, /SEND, and "REAR"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/50 Tell BGFAX (DOS version only) to use 50 line text mode
/ED Tells BGFAX to use "European Date" format. DD-MM-YY.
/NL No Log--tells BGFAX not to use a BGFAX.LOG file at all.
/SD Skip Debug--tells BGFAX to make smaller LOG files by
skipping all debugging information.
/MO Monochrome display mode, for palmtop computers
/PID:nnn Example... /PID:34 will make all log files named
BGFAX34.LOG to keep from having trouble on multi-node
systems.
Valid in "REAR" mode only
~~~~~~~~~~~~~~~~~~~~~~~~~
/DTE:nnnnn If BGFAX has trouble determining the DTE speed when
used in rear-end mode (sometimes happens on FOSSIL
based systems), you can tell BGFAX what DTE speed the
port is set to. Example...
BGFAX /FAX C:\BGFAX 1 Z /DTE:57600
People using BGFAX/DOS in a dos session of Windows 3.11,
Windows 95, and OS/2 may need to use this.
Valid in both "REAR" and /HOST modes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/NS Eliminates the sound that BGFAX plays after successfully
receiving a fax. Registered version only.
/NF Make "FAX" appear on screen after fax received, must be
have the NFAX.COM TSR loaded. Use only on 286 machines
and higher. Do not use under OS/2.
/DIS:nnn Useful for limiting/changing the fax capabilities on
a Class 1 modem. Discussed in detail in another part
of the documentation.
/EX If you are using an EXAR based fax modem, BGFAX will
not perform DLE escapes so that you can get a readable
fax image when receiving. DO NOT USE THIS COMMAND ON
A ROCKWELL OR OTHER TYPE OF FAX MODEM. Most people
in the United States will never need this parameter.
A few people in other countries might need to use it.
Valid only in /HOST mode
~~~~~~~~~~~~~~~~~~~~~~~~
/HOST can also be used as /HOST:nn mode where nn is the number
of minutes of idle time in which BGFAX will exit with an
errorlevel 6. /HOST alone will not exit when idle.
/NH No Hop. In /HOST mode, BGFAX will normally do a
"screen saving" hop. This takes less CPU resources.
/ATO In /HOST mode, use this parameter if you are using
some very old modems in Class 1 mode (some old 2400/9600
modems, as well as the newer USR modems).
/300 Tells BGFAX's /HOST mode to allow 300 bps callers.
Only use this on a Class 2, 2.0, or ZyXEL modem.
Class 1 (when adaptive answering is disabled) uses
a string of "CONNECT" to represent a fax connect,
which is the same as a 300 BPS data caller.
/SB In /HOST mode for the OS/2 version of BGFAX, it causes
BGFAX/2 to _spawn_ the DOBBS.CMD file so that BBS
software such as Maximus/2 can be used successfully.
This switch is meaningless to the DOS version.
/ME In /HOST mode, if you make BGFAX ask the user to hit
<Escape> to load the BBS, normally, if nothing
happens in ten seconds or so, BGFAX times out and
loads the BBS anyway. /ME stands for Must hit Escape
to actually load the BBS. If the user does not,
BGFAX will hang up on them instead of loading the
BBS. Can be used to keep people that don't have
<Esc> keys on their keyboard off your BBS.
/ND In /HOST mode, BGFAX will send a message to any human
(data) callers telling them the BBS is not currently
accepting modem callers. You should never really need
to use this.
Valid only in /SEND mode
~~~~~~~~~~~~~~~~~~~~~~~~
/SEND can also be used as /SEND:nnnnn where nnnnn is the maximum
fax transmit speed, e.g., /SEND:9600
BGFAX /SEND:9600 output.fax 555-1212
In send mode, parameter #2 (output.fax) is the name of the fax
file that is being sent. Parameter #3 is the phone number. The
following switches must come after parameter #3, e.g.,
BGFAX /SEND:9600 output.fax 555-1212 /ER
/ER Extended Results send mode. Discussed earlier.
/HW Tells BGFAX to use hardware flow control (CTS) when
sending faxes. See WHATS.NEW for more info. Applies
only to the DOS version of BGFAX.
/NB Do not create top of page banners when sending faxes.
/C1 Forces BGFAX to use Class 1 mode when sending.
/C2 Forces BGFAX to use Class 2 mode when sending.
/NM Forces BGFAX to use Numeric Mode when sending in Class 1
mode. May be required on some modems like the I-Modem.
Numeric mode being "ATEQV".
/FR:xxxx Overrides the FR= field in BGFAX.CNF when sending
faxes. This text goes in the "From:" field in the
top of page banner. Use underscores instead of
spaces. Example... /FR:BGFAX_Tech_Support
/TO:xxxx Stuffs the "%toNN%" field template. Use underscores
instead of spaces.
/SL:nn Add nn extra scan lines to the top of each page sent.
"nn" is given in SCAN LINES not text lines. 16 scan
lines is about equal to one line of text.
/CI:xxxxx Check ID of remote machine before we /SEND the document.
Example: BGFAX /SEND file.fax 8939124 /ci:3_9124
BGFAX will dial the remote fax machine, and make sure
that a "3 9124" appears somewhere in the remote fax ID.
Note that underscores (_) are used to represent spaces.
If /ER mode is active, if the Check ID fails, BGFAX /SEND
will exit with errorlevel 18. If no /ER, if it fails, it
will exit the standard error exit errorlevel 1. How is this
useful? Well, say someone gets call forwarding on their fax
line, and they have to forward their number to an alternate
fax machine for a week while their fax machine is repaired.
The remote fax machine is probably programmed with an
alternate remote ID, and BGFAX /SEND will abort when it
realized the remote ID does not match what it should, in
the case that you need to send very confidential documents.
Speciality Modes
~~~~~~~~~~~~~~~~
The following mode is only needed in very special cases, and
the average user should have no use for it.
/RING Used instead of /HOST, except that BGFAX will immediately
send the answer string (an= in BGFAX.CNF) to the modem
after BGFAX finishes initializing the modem.
Undocumented
~~~~~~~~~~~~
/HB For internal testing purposes only, /SEND
/XB For internal testing purposes only, /SEND
/SMD For internal testing purposes only, /SEND
-------------------------------------------------------------
ACKNOWLEDGEMENTS
-------------------------------------------------------------
I would like to thank the following people for their assistance
during the initial alpha and beta test phase.
Bill Huther
Brian Wood
Russell Kroll
Ethan Brofman
Ed Lucas
I also think the many people from the Internet and FidoNet that
help out with the on-going public beta program.
US Robotics, Hayes and Supra have also been very helpful in
getting BGFAX to work/work better with their modems.
-------------------------------------------------------------
SHAREWARE
-------------------------------------------------------------
THIS PROGRAM IS SHAREWARE.
If you use this program for more than four weeks you are required
to register it for its low cost of only $25 US DOLLARS.
Please make sure BGFAX works for you BEFORE registering. If you
have a question or problem, I'll answer it (or say I don't know
the answer) whether you have registered or not. I receive so much
mail that it sometimes takes me up to two months to reply to your
question. Again, this is whether you are registered or not.
Voice contact is the only way you will be able to get prompt reply.
Registrations encourage frequent updates.
If you are paying by check or money order, please print out the
REGISTER.FRM file, fill it out, and mail it to my address. Please
try your best to make sure checks are drawn on a US bank.
If you are paying by credit card (Visa, Mastercard, Discover or
American Express) you can (1) mail the form to me, (2) fax the
form to me, (3) netmail the form to me, or (4) call my BBS and
open door #6 and quickly register.
You can also register with Authur Mol in the Netherlands. (See
the REGISTER.NL file for more info. I hope you read Dutch.)
Hamish Moffatt is the registration agent for Australia. (See
the REGISTER.AUS file for more info. This one is in English.)
-------------------------------------------------------------
Regards,
B.J. Guillot
"Don't take a vacation while basting your Rick Roger's turkey."
-- Yan Can Cook, PBS television network